Description

When a mapping contains a field of "type": "alias" whose "path" points to a target that is absent from the flattened mapping — for example a text multi-field (field.keyword) or a removed/renamed field — OpenSearchDataType.validateAliasType() passed a null target into the OpenSearchAliasType constructor, which immediately dereferenced it at super(type.getExprCoreType()). The result was an opaque NullPointerException surfaced to the user with no indication that the real problem is a malformed alias in their mapping:

{
  "error": {
    "reason": "Invalid SQL query",
    "details": "Cannot invoke \"org.opensearch.sql.opensearch.data.type.OpenSearchDataType.getExprCoreType()\" because \"type\" is null",
    "type": "NullPointerException"
  },
  "status": 400
}

Root cause: traverseAndFlatten only expands object/nested properties into dotted keys; it does not add text multi-fields (.keyword), which are stored under OpenSearchTextType.fields. So an alias whose path targets such a field (or a field that no longer exists) resolves to null. The OpenSearchAliasType constructor already guards the alias-to-alias and alias-to-object cases, but those checks run after the super() dereference, so the unresolvable-path case fell through to the NPE.

Fix: Guard the null target in validateAliasType and throw a SemanticCheckException that names the offending alias field and its unresolved path. SemanticCheckException extends QueryEngineException, which JdbcResponseFormatter#getStatus maps to HTTP 400 — an invalid alias mapping is a client error, so this also avoids the misleading HTTP 500 ("internal problem at backend") that a generic exception type would have produced.

After the fix:

{
  "error": {
    "reason": "Invalid SQL query",
    "details": "Alias field [source_alias] refers to unresolved path [source.keyword]. The alias path must point to an existing field in the mapping; a text multi-field (e.g. \"source.keyword.keyword\") or a removed/renamed field is not a valid alias target.",
    "type": "SemanticCheckException"
  },
  "status": 400
}

Valid aliases (including SELECT * over aliases on plain text/keyword fields) are unaffected — the new branch only triggers when the resolved target is null, which previously always threw.

Related Issues

Resolves #5535

Check List

• New functionality includes testing.
• New functionality has been documented.
• New functionality has javadoc added.
• New functionality has a user manual doc added.
• New PPL command checklist all confirmed.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff or -s.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Update: adopt the ErrorReport report-builder interface (#5266)

Per reviewer feedback, the fix now wraps the SemanticCheckException in an ErrorReport (introduced in #5266) instead of throwing it directly. This attaches structured context as the error bubbles up: code = FIELD_NOT_FOUND, stage = ANALYZING, a location chain, the alias_field / alias_path context, and a fix suggestion.

Verified live on both endpoints (both HTTP 400, no regression for valid aliases):

• PPL (_plugins/_ppl) renders the full structured error:

  {
    "error": {
      "reason": "Alias field [source_alias] refers to unresolved path [source.keyword].",
      "code": "FIELD_NOT_FOUND",
      "suggestion": "The alias path must point to an existing field in the mapping; a text multi-field (e.g. \"source.keyword.keyword\") or a removed/renamed field is not a valid alias target.",
      "context": { "stage": "analyzing", "stage_description": "Parsing and validating the query", "alias_field": "source_alias", "alias_path": "source.keyword" },
      "location": ["while preparing and validating the query plan", "while resolving alias fields in the index mapping"],
      "type": "SemanticCheckException"
    },
    "status": 400
  }

• SQL (_plugins/_sql) still returns a clear 400 — RestSqlAction unwraps ErrorReport to its SemanticCheckException cause for status classification. Note: JdbcResponseFormatter does not yet render the ErrorReport structure (it reports type: "ErrorReport" with just details); teaching the JDBC formatter to render the structured fields is a reasonable follow-up but is intentionally out of scope here to keep this change focused.

Tests: unit test asserts the ErrorReport code/stage/context/cause; a PPL IT in CalciteErrorReportStageIT asserts the structured FIELD_NOT_FOUND error; the SQL IT in QueryValidationIT asserts the 400.